<html>
<head>
<title>C++ Annotations Version 6.5.0</title>
</head>
<body text="black" bgcolor="white">
<hr>
<ul>
    <li> <a href="cplusplus.html">Table of Contents</a>
    <li> <a href="cplusplus03.html">Previous Chapter</a>
    <li> <a href="cplusplus05.html">Next Chapter</a>
</ul>
<hr>
<a name="String"></a><a name="l55"></a>
<h1>Chapter 4: The `string' data type</h1>
<a name="string"></a>

<blockquote>
    <em>
        Don't hesitate to send in feedback: send an e-mail if you like the
        C++ Annotations; if you think that important material was omitted;
        if you find errors or typos in the text or the code examples;
        or if you just feel like e-mailing. Send your e-mail to
        <a href="mailto:f.b.brokken@rug.nl">Frank B. Brokken</a>.
<p>
<strong>Please</strong> state the document version you're referring to, as found in
        the title (in this document: 6.5.0) and please state chapter and
        paragraph name or number you're referring to.
<p>
All received mail is processed conscientiously, and received
        suggestions for improvements will usually have been processed by the
        time a new version of the Annotations is released. Except for the
        incidental case I will normally not acknowledge the receipt of
        suggestions for improvements. Please don't interpret this as me not
        appreciating your efforts.
    </em>
</blockquote>
<p>
<a name="string/string"></a><strong>C++</strong> offers a large number of facilities to implement solutions for common
problems. Most of these facilities are part of the <em>Standard Template
Library</em> or they are implemented as <em>generic algorithms</em> (see chapter
<a href="cplusplus17.html#STL">17</a>).
<p>
Among the facilities <strong>C++</strong> programmers have developed over and over again
are those for manipulating chunks of text,
commonly called <em>strings</em>. The <strong>C</strong> programming language offers
rudimentary string support: the <a name="an249"></a>
<em>ASCII-Z</em>
terminated series of characters is the foundation on which a large amount of
code has been built&nbsp;(We define an
    <a name="an250"></a>
ASCII-Z string as a series of ASCII-characters terminated by the
ASCII-character zero (hence -Z), which has the value zero, and should not be
confused with character <a name="an251"></a>
<code>'0'</code>, which usually has the value <a name="an252"></a>
<code>0x30</code>).
<p>
Standard <strong>C++</strong> now offers a <a name="an253"></a>
<code>string</code> type. In order to use
<code>string</code>-type objects, the header file <code>string</code> must be included in
sources.
<p>
Actually, <code>string</code> objects are <em>class type</em> variables, and the <code>class</code>
is formally introduced in chapter <a href="cplusplus06.html#Classes">6</a>. However, in order to use a
string, it is not necessary to know what a class is. In this section the
operators that are available for strings and several other operations are
discussed. The operations that can be performed on strings take the form
    <pre>
        stringVariable.operation(argumentList)
</pre>
For example, if <code>string1</code> and <code>string2</code> are variables of type <code>string</code>,
then
    <pre>
        string1.compare(string2)
</pre>
 can be used to compare both strings. A
function like <code>compare()</code>, which is part of the <code>string</code>-class is called a
<a name="an254"></a>
<em>member function</em>. The <code>string</code> class offers a large number of these
member functions, as well as extensions of some well-known operators, like the
assignment (<code>=</code>) and the comparison operator (<code>==</code>). These operators and
functions are discussed in the following sections.
<p>
<a name="l56"></a>
<h2>4.1: Operations on strings</h2>
<a name="string/ops"></a>Some of the operations that can be performed on strings return indices within
the strings. Whenever such an operation fails to find an appropriate index,
the <em>value</em> <a name="an255"></a>
<code>string::npos</code> is returned. This value is a (symbolic) value
of type <a name="an256"></a>
<code>string::size_type</code>, which is (for all practical purposes) an
(<code>unsigned</code>) <code>int</code>.
<p>
Note that in all operations with <code>strings</code> both <code>string</code> objects
and <code>char const *</code> values and variables can be used.
<p>
Some <code>string</code>-members use <em>iterators</em>. Iterators will be
covered in section <a href="cplusplus17.html#ITERATORS">17.2</a>. The member functions using iterators are
listed in the next section (<a href="cplusplus04.html#STRINGOVERVIEW">4.2</a>), they are not further
illustrated below.
<p>
The following operations can be performed on strings:
    <ul>
    <li> <a name="an257"></a>
 Initialization: String objects can
be <em>initialized</em>. For the initialization a plain <a name="an258"></a>
<code>ASCII-Z</code> string, another
<code>string</code> object, or an implicit initialization can be used. In the example,
note that the implicit initialization does not have an argument, and may not
use an argument list. Not even empty.
        <pre>
    #include &lt;string&gt;

    using namespace std;

    int main()
    {
        string stringOne("Hello World");  // using plain ascii-Z
        string stringTwo(stringOne);      // using another string object
        string stringThree;               // implicit initialization to "". Do
                                          // not use the form `stringThree()'
        return 0;
    }
</pre>
    <li> <a name="an259"></a>
 Assignment: String objects can be assigned to
each other. For this the assignment operator (i.e., the <code>=</code> operator) can be
used, which accepts both a <code>string</code> object and a <strong>C</strong>-style character
string as its right-hand argument:
        <pre>
    #include &lt;string&gt;
    using namespace std;

    int main()
    {
        string stringOne("Hello World");
        string stringTwo;

        stringTwo = stringOne;      // assign stringOne to stringTwo
        stringTwo = "Hello world";  // assign a C-string to StringTwo

        return 0;
    }
</pre>
    <li> <a name="an260"></a>
 String to ASCII-Z conversion: In the
previous example a standard <strong>C</strong>-string (an ASCII-Z string) was implicitly
converted to a <code>string</code>-object. The reverse conversion (converting a
<code>string</code> object to a standard <strong>C</strong>-string) is not performed
automatically. In order to obtain the <code>C</code>-string that is stored within the
<code>string</code> object itself, the member function <code>c_str()</code>, which returns a
<code>char const *</code>, can be used:
        <pre>
    #include &lt;iostream&gt;
    #include &lt;string&gt;
    using namespace std;

    int main()
    {
        string stringOne("Hello World");
        char const *cString = stringOne.c_str();

        cout &lt;&lt; cString &lt;&lt; endl;

        return 0;
    }
</pre>
    <li> <a name="an261"></a>
 String elements: The individual elements of a
string object can be accessed for reading or writing. For this operation the
subscript-operator (<code>[]</code>) is available, but there is <em>no</em>
    <a name="an262"></a>
string pointer dereferencing operator (<code>*</code>). The subscript operator
does not perform range-checking. <a name="an263"></a>
 If range
checking is required the <a name="an264"></a>
<code>string::at()</code> member function should be used:
        <pre>
    #include &lt;iostream&gt;
    #include &lt;string&gt;
    using namespace std;

    int main()
    {
        string stringOne("Hello World");

        stringOne[6] = 'w';         // now "Hello world"
        if (stringOne[0] == 'H')
            stringOne[0] = 'h';     // now "hello world"

        //  *stringOne = 'H';       // THIS WON'T COMPILE

        stringOne = "Hello World";  // Now using the at()

                                    // member function:
        stringOne.at(6) =
                stringOne.at(0);    // now "Hello Horld"
        if (stringOne.at(0) == 'H')
            stringOne.at(0) = 'W';  // now "Wello Horld"

        return 0;
    }
</pre>
    When an illegal index is passed to the <code>at()</code> member function, the
program aborts (actually, an <em>exception</em> is generated, which could be
caught. Exceptions are covered in chapter <a href="cplusplus08.html#EXCEPTIONS">8</a>).
    <li> <a name="an265"></a>
 Comparisons: Two strings can be compared for
(in)equality or ordering, using the <code>==, !=, &lt;, &lt;=, &gt;</code> and <code>&gt;=</code> operators
or the <a name="an266"></a>
<code>string::compare()</code> member function. The <code>compare()</code> member
function comes in several flavors (see section <a href="cplusplus04.html#STRINGMEMBERS">4.2.4</a> for
details). E.g.:
        <ul>
        <li><code>int string::compare(string const &amp;other)</code>: this variant offers
a bit more information than the comparison-operators do.  The return value of
the <code>string::compare()</code> member function may be used for
    <a name="an267"></a>
lexicographical ordering: a negative value is returned if the string
stored in the string object using the <code>compare()</code> member function (in the
example: <code>stringOne</code>) is located earlier in the
    <a name="an268"></a>
<em>ASCII collating sequence</em> than the string stored in the string
object passed as argument.
        <pre>
    #include &lt;iostream&gt;
    #include &lt;string&gt;
    using namespace std;

    int main()
    {
        string stringOne("Hello World");
        string stringTwo;

        if (stringOne != stringTwo)
            stringTwo = stringOne;

        if (stringOne == stringTwo)
            stringTwo = "Something else";

        if (stringOne.compare(stringTwo) &gt; 0)
            cout &lt;&lt; "stringOne after stringTwo in the alphabet\n";
        else if (stringOne.compare(stringTwo) &lt; 0)
            cout &lt;&lt; "stringOne before stringTwo in the alphabet\n";
        else
            cout &lt;&lt; "Both strings are the same\n";

        // Alternatively:

        if (stringOne &gt; stringTwo)
            cout &lt;&lt;
            "stringOne after stringTwo in the alphabet\n";
        else if (stringOne &lt; stringTwo)
            cout &lt;&lt;
            "stringOne before stringTwo in the alphabet\n";
        else
            cout &lt;&lt; "Both strings are the same\n";

        return 0;
    }
</pre>
    Note that there is no member function to perform a
        <a name="an269"></a>
case insensitive comparison of strings.
        <li><code>int string::compare(string::size_type pos, size_t n, string
const &amp;other)</code>: the first argument indicates the position in the current
string that should be compared; the second argument indicates the number of
characters that should be compared (if this value exceeds the number of
characters that are actually available, only the available characters are
compared); the third argument indicates the string which is compared to the
current string.
        <li> More variants of <code>string::compare()</code> are available. As stated,
refer to section <a href="cplusplus04.html#STRINGMEMBERS">4.2.4</a> for details.
        </ul>
    The following example illustrates the <code>compare()</code> function:
        <pre>
    #include &lt;iostream&gt;
    #include &lt;string&gt;
    using namespace std;

    int main()
    {
        string stringOne("Hello World");

            // comparing from a certain offset in stringOne
        if (!stringOne.compare(1, stringOne.length() - 1, "ello World"))
            cout &lt;&lt; "comparing 'Hello world' from index 1"
                    " to 'ello World': ok\n";

            // the number of characters to compare (2nd arg.)
            // may exceed the number of available characters:
        if (!stringOne.compare(1, string::npos, "ello World"))
            cout &lt;&lt; "comparing 'Hello world' from index 1"
                    " to 'ello World': ok\n";

            // comparing from a certain offset in stringOne over a
            // certain number of characters in "World and more"
            // This fails, as all of the chars in stringOne
            // starting at index 6 are compared, not just
            // 3 chars in "World and more"
        if (!stringOne.compare(6, 3, "World and more"))
            cout &lt;&lt;
            "comparing 'Hello World' from index 6 over"
            " 3 positions to 'World and more': ok\n";
        else
            cout &lt;&lt; "Unequal (sub)strings\n";

            // This one will report a match, as only 5 characters are
            // compared of the  source and target strings
        if (!stringOne.compare(6, 5, "World and more", 0, 5))
            cout &lt;&lt;
            "comparing 'Hello World' from index 6 over"
            " 5 positions to 'World and more': ok\n";
        else
            cout &lt;&lt; "Unequal (sub)strings\n";
    }
    /*
            Generated output:

        comparing 'Hello world' from index 1 to 'ello World': ok
        comparing 'Hello world' from index 1 to 'ello World': ok
        Unequal (sub)strings
        comparing 'Hello World' from index 6 over 5 positions to
                    'World and more': ok
    */
</pre>
        <li> <a name="an270"></a>
 Appending: A <code>string</code> can be appended to
another string. For this the <code>+=</code> operator can be used, as well as the
<code>string &amp;string::append()</code> member function.
<p>
Like the <code>compare()</code> function, the <code>append()</code> member function may have
extra arguments. The first argument is the string to be appended, the
second argument specifies the index position of the first character that will
be appended. The third argument specifies the number of characters that will
be appended.  If the first argument is of type <code>char const *</code>, only a second
argument may be specified. In that case, the second argument specifies the
number of characters of the first argument that are appended to the <code>string</code>
object.  Furthermore, the <code>+</code> operator can be used to append two strings
within an expression:
        <pre>
    #include &lt;iostream&gt;
    #include &lt;string&gt;

    using namespace std;

    int main()
    {
        string stringOne("Hello");
        string stringTwo("World");

        stringOne += " " + stringTwo;

        stringOne = "hello";
        stringOne.append(" world");
                                        // append 5 characters:
        stringOne.append(" ok. &gt;This is not used&lt;", 5);

        cout &lt;&lt; stringOne &lt;&lt; endl;

        string stringThree("Hello");
                                        // append " world":
        stringThree.append(stringOne, 5, 6);

        cout &lt;&lt; stringThree &lt;&lt; endl;
    }
</pre>
    The <code>+</code> operator can be used in cases where at least one term of the
<code>+</code> operator is a <code>string</code> object (the other term can be a <code>string, char
const *</code> or <code>char</code>).
<p>
When neither operand of the <code>+</code> operator is a <code>string</code>, at least one
operand must be converted to a <code>string</code> object first. An easy way
to do this is to use an <a name="an271"></a>
<em>anonymous string</em> object:
        <pre>
        string("hello") + " world";
</pre>
        <li> <a name="an272"></a>
 Insertions: The <code>string &amp;string::insert()</code> member
function to insert (parts of) a <code>string</code> has at least two, and at most four
arguments:
        <ul>
        <li> The first argument is the offset in the current <code>string</code> object
    where another string should be inserted.
        <li> The second argument is the string to be inserted.
        <li> The third argument specifies the index position of the
    first character in the provided <code>string</code>-argument that will be inserted.
        <li> The fourth argument specifies the number of characters that will
            be inserted.
        </ul>
    If the first argument is of type <code>char const *</code>, the fourth argument is
not available. In that case, the third argument indicates the number of
characters of the provided <code>char const *</code> value that will be inserted.
        <pre>
    #include &lt;string&gt;

    int main()
    {
        string
            stringOne("Hell ok.");
                            // Insert "o " at position 4
        stringOne.insert(4, "o ");

        string
            world("The World of C++");

                            // insert "World" into stringOne
        stringOne.insert(6, world, 4, 5);

        cout &lt;&lt; "Guess what ? It is: " &lt;&lt; stringOne &lt;&lt; endl;
    }
</pre>
    Several variants of <code>string::insert()</code> are available. See section
<a href="cplusplus04.html#STRINGOVERVIEW">4.2</a> for details.
        <li> <a name="an273"></a>
 Replacements: At times, the contents of
<code>string</code> objects must be replaced by other information. To replace parts of
the contents of a <code>string</code> object by another string the member function
<code>string &amp;string::</code><code>replace()</code> can be used.
    The member function has at least three and possibly five arguments, having
the following meanings
(see section <a href="cplusplus04.html#STRINGOVERVIEW">4.2</a> for overloaded versions of
<code>replace()</code>, using different types of arguments):
    <ul>
    <li> The first argument indicates the position of the first character that
must be replaced
    <li> The second argument gives the number of characters that
must be replaced.
    <li> The third argument defines the replacement text (a
<code>string</code> or <code>char const *</code>).
    <li> The fourth argument specifies the index position of
the first character in the provided <code>string</code>-argument that will be inserted.
    <li> The fifth argument can be used to specify the number of
characters that will be inserted.
    </ul>
    If the third argument is of type <code>char const *</code>, the fifth argument is
not available. In that case, the fourth argument indicates the number of
characters of the provided <code>char const *</code> value that will be inserted.
<p>
The following example shows a very simple <em>file changer</em>: it reads lines
from <code>cin</code>, and replaces occurrences of a `searchstring' by a
`replacestring'. Simple tests for the correct number of arguments and the
contents of the provided strings (they should be unequal) are applied as well.
<a name="REPLACECC"></a>
        <pre>
    #include &lt;iostream&gt;
    #include &lt;string&gt;

    using namespace std;

    int main(int argc, char **argv)
    {
        if (argc == 3)
        {
            cerr &lt;&lt; "Usage: &lt;searchstring&gt; &lt;replacestring&gt; to process "
                                                                  "stdin\n";
            return 1;
        }

        string search(argv[1]);
        string replace(argv[2]);

        if (search == replace)
        {
            cerr &lt;&lt; "The replace and search texts should be different\n";
            return 1;
        }

        string line;
        while (getline(cin, line))
        {
            string::size_type idx = 0;
            while (true)
            {
                idx = line.find(search, idx); // find(): another string member
                                              //         see `searching' below
                if (idx == string::npos)
                    break;

                line.replace(idx, search.size(), replace);
                idx += replace.length();     // don't change the replacement
            }
            cout &lt;&lt; line &lt;&lt; endl;
        }
        return 0;
    }
</pre>
        <li> <a name="an274"></a>
  Swapping: The member function
        <code>string &amp;string::swap(string &amp;other)</code>
    swaps the contents of two <code>string</code>-objects. For example:
        <pre>
    #include &lt;iostream&gt;
    #include &lt;string&gt;
    using namespace std;

    int main()
    {
        string stringOne("Hello");
        string stringTwo("World");

        cout &lt;&lt; "Before: stringOne: " &lt;&lt; stringOne &lt;&lt; ", stringTwo: "
            &lt;&lt; stringTwo &lt;&lt; endl;

        stringOne.swap(stringTwo);

        cout &lt;&lt; "After: stringOne: " &lt;&lt; stringOne &lt;&lt; ", stringTwo: "
            &lt;&lt; stringTwo &lt;&lt; endl;
    }
</pre>
        <li> <a name="an275"></a>
  Erasing: The member function <code>string
&amp;string::erase()</code> removes characters from a <code>string</code>. The standard form has
two optional arguments:
        <ul>
        <li> If no arguments are specified, the stored string is erased
    completely: it becomes the empty string (<code>string()</code> or <code>string("")</code>).
        <li> The first argument may be used to specify the offset of the first
    character that must be erased.
        <li> The second argument may be used to specify the number of
            characters that are to be erased.
        </ul>
    See section <a href="cplusplus04.html#STRINGOVERVIEW">4.2</a> for overloaded versions of <code>erase()</code>. An
example of the use of <code>erase()</code> is given below:
        <pre>
    #include &lt;iostream&gt;
    #include &lt;string&gt;
    using namespace std;

    int main()
    {
        string stringOne("Hello Cruel World");

        stringOne.erase(5, 6);

        cout &lt;&lt; stringOne &lt;&lt; endl;

        stringOne.erase();

        cout &lt;&lt; "'" &lt;&lt; stringOne &lt;&lt; "'\n";
    }
</pre>
        <li> <a name="an276"></a>
 Searching: To find <a name="an277"></a>
substrings in a
<code>string</code> the member function <code>string::size_type</code>
    <code>string::find()</code> can be used. This function looks for the string that is
provided as its first argument in the <code>string</code> object calling <code>find()</code> and
returns the index of the first character of the substring if found. If the
string is not found <code>string::npos</code> is returned. The member function
<code>rfind()</code> looks for the substring from the end of the <code>string</code> object back
to its beginning. An example using <code>find()</code> was given
<a href="cplusplus04.html#REPLACECC">earlier.</a>
        <li> <a name="an278"></a>
Substrings: To extract a substring from a <code>string</code> object,
the member function <code>string</code><code>string::substr()</code> is
available. The returned <code>string</code> object contains a copy of the substring in
the <code>string</code>-object calling <code>substr()</code> The <code>substr()</code> member function
has two optional arguments:
        <ul>
        <li> Without arguments, a copy of the <code>string</code> itself is returned.
        <li> The first argument may be used to specify the offset of the first
            character to be returned.
        <li> The second argument may be used to specify the number of
            characters that are to be returned.
        </ul>
    For example:
        <pre>
    #include &lt;iostream&gt;
    #include &lt;string&gt;
    using namespace std;

    int main()
    {
        string stringOne("Hello World");

        cout &lt;&lt; stringOne.substr(0, 5)  &lt;&lt; endl
             &lt;&lt; stringOne.substr(6)     &lt;&lt; endl
             &lt;&lt; stringOne.substr()      &lt;&lt; endl;
    }
</pre>
        <li> <a name="an279"></a>
Character set searches: Whereas <code>find()</code> is used to find a
substring, the functions <code>find_first_of(), find_first_not_of(),
find_last_of()</code> and <code>find_last_not_of()</code> can be used to find <em>sets</em> of
characters (Unfortunately, regular expressions are not supported here). The
following program reads a line of text from the standard input stream, and
displays the substrings starting at the first vowel, starting at the last
vowel, and starting at the first non-digit:
        <pre>
    #include &lt;iostream&gt;
    #include &lt;string&gt;
    using namespace std;

    int main()
    {
        string line;

        getline(cin, line);

        string::size_type pos;

        cout &lt;&lt; "Line: " &lt;&lt; line &lt;&lt; endl
            &lt;&lt; "Starting at the first vowel:\n"
            &lt;&lt; "'"
                &lt;&lt; (
                    (pos = line.find_first_of("aeiouAEIOU"))
                    != string::npos ?
                        line.substr(pos)
                    :
                        "*** not found ***"
                    ) &lt;&lt; "'\n"
            &lt;&lt; "Starting at the last vowel:\n"
            &lt;&lt; "'"
                &lt;&lt; (
                    (pos = line.find_last_of("aeiouAEIOU"))
                    != string::npos ?
                        line.substr(pos)
                    :
                        "*** not found ***"
                    ) &lt;&lt; "'\n"
            &lt;&lt; "Starting at the first non-digit:\n"
            &lt;&lt; "'"
                &lt;&lt; (
                    (pos = line.find_first_not_of("1234567890"))
                    != string::npos ?
                        line.substr(pos)
                    :
                        "*** not found ***"
                    ) &lt;&lt; "'\n";
    }
</pre>
        <li> <a name="an280"></a>
 String size: The number of characters that are
stored in a string are obtained by the <code>size()</code> member function, which, like
the standard <strong>C</strong> function <a name="an281"></a>
<code>strlen()</code> does not include the terminating
ASCII-Z character. For example:
     <pre>
    #include &lt;iostream&gt;
    #include &lt;string&gt;
    using namespace std;

    int main()
    {
        string stringOne("Hello World");

        cout &lt;&lt; "The length of the stringOne string is "
            &lt;&lt; stringOne.size() &lt;&lt; " characters\n";
    }
</pre>
        <li> <a name="an282"></a>
 Empty strings: The <code>size()</code> member function
can be used to determine whether a string holds no characters. Alternatively,
the <a name="an283"></a>
<code>string::empty()</code> member function can be used:
         <pre>
    #include &lt;iostream&gt;
    #include &lt;string&gt;
    using namespace std;

    int main()
    {
        string stringOne;

        cout &lt;&lt; "The length of the stringOne string is "
            &lt;&lt; stringOne.size() &lt;&lt; " characters\n"
                "It is " &lt;&lt; (stringOne.empty() ? "" : " not ")
            &lt;&lt; "empty\n";

        stringOne = "";

        cout &lt;&lt; "After assigning a \"\"-string to a string-object\n"
                "it is " &lt;&lt; (stringOne.empty() ? "also" : " not")
            &lt;&lt; " empty\n";
    }
</pre>
        <li> <a name="an284"></a>
 Resizing strings: If the size of a string is
not enough (or if it is too large), the member function <code>void
string::resize()</code> can be used to make it longer or shorter. Note that
operators like <code>+=</code> automatically resize a <code>string</code> when needed.
    <li> <a name="an285"></a>
 Reading a line from a stream into a string: The
function
        <pre>
    istream &amp;getline(istream &amp;instream, string &amp;target, char delimiter)
</pre>
may be used to read a line of text (up to the first delimiter or the
end of the stream) from <code>instream</code> (note that <code>getline()</code> is not a
<em>member</em> function of the class <code>string</code>).
<p>
The delimiter has a default value <code>'\n'</code>. It is removed from <code>instream</code>,
but it is <em>not</em> stored in <code>target</code>.  The member <code>istream::eof()</code> may be
called to determine whether the delimiter was found. If it returns <code>true</code>
the delimiter was <em>not</em> found (see chapter <a href="cplusplus05.html#IOStreams">5</a> for details about
<code>istream</code> objects). The function <code>getline()</code> was used in several earlier
examples (e.g., with the <a href="cplusplus04.html#REPLACECC">replace()</a> member function).
    <li> <a name="an286"></a>
 A <code>string</code> variables may be extracted from
a stream. Using the construction
            <pre>
    istr &gt;&gt; str;
</pre>
    where <code>istr</code> is an <code>istream</code> object, and <code>str</code> is a <code>string</code>, the
next consecutive series of non-blank characters will be assigned to
<code>str</code>. Note that by default the extraction operation will skip any
blanks that precede the characters that are extracted from the stream.
    </ul>
<p>
<a name="STRINGOVERVIEW"></a><a name="l57"></a>
<h2>4.2: Overview of operations on strings</h2>
<a name="string/overview"></a>In this section the available operations on strings are summarized. There are
four subparts here: the <code>string</code>-initializers, the <code>string</code>-iterators, the
<code>string</code>-operators and the <code>string</code>-member functions.
<p>
The member functions are ordered alphabetically by the name of the
operation. Below, <code>object</code> is a <code>string</code>-object, and <code>argument</code> is
either a <code>string const &amp;</code> or a <code>char const *</code>, unless overloaded versions
tailored to <code>string</code> and <code>char const *</code> parameters are explicitly
mentioned. <code>Object</code> is used in cases where a <code>string</code> object is
initialized or given a new value. The entity referred to by <code>argument</code>
always remains unchanged.
<p>
Furthermore, <code>opos</code> indicates an offset into the <code>object</code> string, <code>apos</code>
indicates an offset into the <code>argument</code> string. Analogously, <code>on</code>
indicates a number of characters in the <code>object</code> string, and <code>an</code>
indicates a number of characters in the <code>argument</code> string. Both <code>opos</code> and
<code>apos</code> must refer to existing offsets, or an exception will be generated. In
contrast to this, <code>an</code> and <code>on</code> may exceed the number of available
characters, in which case only the available characters will be considered.
<p>
When streams are involved, <code>istr</code> indicates a stream from which information
is extracted, <code>ostr</code> indicates a stream into which information is inserted.
<p>
With member functions the types of the parameters are given in a
function-prototypical way. With several member functions <em>iterators</em> are
used. At this point in the Annotations it's a bit premature to discuss
iterators, but for referential purposes they have to be mentioned
nevertheless. So, a forward reference is used here: see section <a href="cplusplus17.html#ITERATORS">17.2</a>
for a more detailed discussion of <em>iterators</em>. Like <code>apos</code> and <code>opos</code>,
iterators must also refer to an existing character, or to an available
iterator range of the string to which they refer.
<p>
Finally, note that all <code>string</code>-member functions returning indices in
<code>object</code> return the predefined constant <a name="an287"></a>
<code>string::npos</code> if no
suitable index could be found.
<p>
<a name="l58"></a>
<h3>4.2.1: Initializers</h3>
    <a name="string/initializers"></a>    The following <code>string</code> constructors <a name="an288"></a>
 are
available:
        <ul>
        <li><code>string object</code>:
            <blockquote>Initializes <code>object</code> to an empty string.</blockquote>
        <li><code>string object(string::size_type no, char c)</code>:
            <blockquote>Initializes <code>object</code> with <code>no</code> characters <code>c</code>.</blockquote>
        <li><code>string object(string argument)</code>:
            <blockquote>Initializes <code>object</code> with <code>argument</code>.</blockquote>
        <li><code>string object = argument</code>:
            <blockquote>Initializes <code>object</code> with <code>argument</code>. This is an
alternative form of the previous initialization.</blockquote>
        <li><code>string object(string argument, string::size_type apos,
                                                string::size_type an = pos)</code>:
            <blockquote>Initializes <code>object</code> with <code>argument</code>,
            using <code>an</code> characters of <code>argument</code>, starting at index
            <code>apos</code>.</blockquote>
        <li><code>string object(InputIterator begin, InputIterator end)</code>:
            <blockquote>Initializes <code>object</code> with the range of characters implied
            by the provided <code>InputIterators</code>. Iterators are covered in
            detail in section <a href="cplusplus17.html#ITERATORS">17.2</a>, but can (for the time being) be
            interpreted as pointers to characters. See also the next section.</blockquote>
        </ul>
<p>
<a name="l59"></a>
<h3>4.2.2: Iterators</h3>
    <a name="string/iterators"></a>        See section <a href="cplusplus17.html#ITERATORS">17.2</a> for details about <em>iterators</em>. As a quick
introduction to iterators: an iterator acts like a pointer, and pointers can
often be used in situations where iterators are requested. Iterators almost
always come in pairs: the begin-iterator points to the first entity that will
be considered, the end-iterator points just beyond the last entity that will
be considered. Iterators play an important role in the context of <em>generic
algorithms</em> (cf. chapter <a href="cplusplus17.html#STL">17</a>).
        <ul>
        <li> Forward iterators are returned by the members:
            <ul>
            <li> <a name="an289"></a>
<code>string::begin()</code>, pointing to the first character inside
the string object.
            <li> <a name="an290"></a>
<code>string::end()</code>, pointing beyond the last character
inside the string object.
            </ul>
        <li> Reverse iterators are also iterators, but they are used to step
through a range in a reversed direction. Reverse iterators
are returned by the members:
            <ul>
            <li> <a name="an291"></a>
<code>string::rbegin()</code>, which can be considered to be an
iterator pointing to the last character inside the string object.
            <li> <a name="an292"></a>
<code>string::rend()</code>, which can be considered to be an iterator
pointing before the first character inside the string object.
            </ul>
        </ul>
<p>
<a name="l60"></a>
<h3>4.2.3: Operators</h3>
    <a name="string/operators"></a>The following <a name="an293"></a>
string operators are available:
        <ul>
        <li><code>object = argument</code>.
            <blockquote>Assignment of <code>argument</code> to an existing string
<code>object</code>.</blockquote>
        <li><code>object = c</code>.
            <blockquote>Assignment of <code>char c</code> to <code>object</code>.</blockquote>
        <li><code>object += argument</code>.
            <blockquote>Appends <code>argument</code> to <code>object</code>. <code>Argument</code> may also be
a <code>char</code> expression.</blockquote>
        <li><code>argument1 + argument2</code>.
            <blockquote>Within expressions, <code>strings</code> may be added. At least one
term of the expression (the left-hand term or the right-hand term) should be a
<code>string</code> object. The other term may be a <code>string</code>, a <code>char const *</code>
value or a <code>char</code> expression, as illustrated by the following example:</blockquote>
            <pre>
    void fun()
    {
        char const *asciiz = "hello";
        string first = "first";
        string second;

            // all expressions compile ok:
        second = first + asciiz;
        second = asciiz + first;
        second = first + 'a';
        second = 'a' + first;
    }
</pre>
        <li><code>object[string::size_type opos]</code>.
            <blockquote>The subscript-operator may be used to retrieve <code>object</code>'s
individual characters, or to assign new values to individual characters of
<code>object</code> or to retrieve these characters. There is no range-checking. If
range checking is required, use the <code>at()</code> member function.</blockquote>
        <li><code>argument1 == argument2</code>.
            <blockquote>The equality operator (<a name="an294"></a>
<code>==</code>) may be used to compare a
<code>string</code> object to another <code>string</code> or <code>char const *</code> value. The <a name="an295"></a>
<code>!=</code>
operator is available as well. The return value for both is a <code>bool</code>. For
two identical strings <code>==</code> returns <a name="an296"></a>
<code>true</code>, and <code>!=</code> returns <a name="an297"></a>
<code>false</code>.</blockquote>
        <li><code>argument1 &lt; argument2</code>.
            <blockquote>The less-than operator may be used to compare the ordering
within the Ascii-character set of <code>argument1</code> and <code>argument2</code>. The
operators <code>&lt;=, &gt;</code> and <code>&gt;=</code> are available as well.</blockquote>
        <li><code>ostr</code> << <code>object</code>.
            <blockquote>The insertion-operator may be used with <code>string</code> objects.</blockquote>
        <li><code>istr</code> >> <code>object</code>.
            <blockquote>The extraction-operator may be used with <code>string</code>
objects. It operates analogously to the extraction of characters into a
character array, but <code>object</code> is automatically resized to the required
number of characters.</blockquote>
        </ul>
<p>
<a name="STRINGMEMBERS"></a><a name="l61"></a>
<h3>4.2.4: Member functions</h3>
    <a name="string/members"></a>The string member functions are listed in alphabetical order. The member name,
prefixed by the <code>string</code>-class is given first. Then the full prototype and a
description are given. Values of the type <a name="an298"></a>
<code>string::size_type</code> represent
index positions within a <code>string</code>. For all practical purposes, these values
may be interpreted as <code>unsigned</code>.
<p>
The special value <a name="an299"></a>
<code>string::npos</code>, defined by the string class, represents a
non-existing index. This value is returned by all members returning indices
when they could not perform their requested tasks. Note that the string's
<em>length</em> is not returned as a valid index. E.g., when calling a member
`<code>find_first_not_of(" ")</code>' (see below) on a <code>string</code> object holding 10
blank space characters, <code>npos</code> is returned, as the string only contains
blanks.  The final 0-byte that is used in <strong>C</strong> to indicate the end of a
<code>ASCII-Z</code> string is <em>not</em> considered part of a <strong>C++</strong> string, and so the
member function will return <code>npos</code>, rather than <code>length()</code>.
<p>
In the following overview, `<code>size_type</code>' should always be read as
    `<a name="an300"></a>
<code>string::size_type</code>'.
        <ul>
<p>
<li> <a name="an301"></a>
 <code>char &amp;string::at(size_type opos)</code>:
            <blockquote>The character (reference) at the indicated position is
returned (it may be reassigned). The member function performs range-checking,
aborting the program if an invalid index is passed.</blockquote>
<p>
<li> <a name="an302"></a>

            <code>string &amp;string::append(InputIterator begin, InputIterator end)</code>:
            <blockquote> Using this member function the range of characters implied
by the <code>begin</code> and <code>end InputIterators</code> are appended to the <code>string</code>
object.</blockquote>
<p>
<li><code>string &amp;string::append(string argument, size_type apos, size_type
an)</code>:
            <blockquote>
            <ul>
            <li> If only <code>argument</code> is provided, it is appended to the
<code>string</code> object.
            <li> If <code>apos</code> is provided as well, <code>argument</code> is appended
from index position <code>apos</code> until the end of <code>argument</code>.
            <li> If <code>an</code> is provided too, <code>an</code> characters of <code>argument</code>,
starting at index position <code>apos</code> are appended to the <code>string</code> object.
            </ul>
    If <code>argument</code> is of type <code>char const *</code>, the second parameter <code>apos</code>
is not available.  So, with <code>char const *</code> arguments, either <em>all</em>
characters or an <em>initial subset</em> of the characters of the provided <code>char
const *</code> argument are appended to the <code>string</code> object. Of course, if
<code>apos</code> and <code>an</code> <em>are</em> specified in this case, <code>append()</code> can still be
used: the <code>char const *</code> argument will then implicitly be converted to a
<code>string const &amp;</code>.</blockquote>
<p>
<li><code>string &amp;string::append(size_type n, char c)</code>:
        <blockquote>Using this member function, <code>n</code> characters <code>c</code> can be
appended to the <code>string</code> object.
            </blockquote>
<p>
<li> <a name="an303"></a>

        <code>string &amp;string::assign(string argument, size_type apos,
size_type an)</code>:
            <blockquote>
            <ul>
            <li> If only <code>argument</code> is provided, it is assigned to the
<code>string</code> object.
            <li> If <code>apos</code> is specified as well, a substring of
<code>argument</code> object, starting at offset position <code>apos</code>, is
assigned to the <code>string</code> object calling this member.
            <li> If <code>an</code> is provided too, a substring of <code>argument</code>
object, starting at offset position <code>apos</code>, containing at most <code>an</code>
characters, is assigned to the <code>string</code> object calling this member.
            </ul>
    If <code>argument</code> is of type <code>char const *</code>, no parameter <code>apos</code> is
available.  So, with <code>char const *</code> arguments, either <em>all</em> characters or
an <em>initial subset</em> of the characters of the provided <code>char const *</code>
argument are assigned to the <code>string</code> object. As with the
<code>string::append()</code> member, a <code>char const *</code> argument <em>may</em> be used, but
it will be converted to a <code>string</code> object first.</blockquote>
<p>
<li><code>string &amp;string::assign(size_type n, char c)</code>:
        <blockquote>
            Using this member function, <code>n</code> characters <code>c</code> can be assigned
to the <code>string</code> object.</blockquote>
<p>
<li> <a name="an304"></a>

            <code>size_type string::capacity()</code>:
            <blockquote>returns the number of characters that can currently be
stored inside the <code>string</code> object.</blockquote>
<p>
<li> <a name="an305"></a>

        <code>int string::compare(string argument)</code>:
            <blockquote>This member function can be used to compare (according to
the ASCII-character set) the text stored in the <code>string</code> object and in
<code>argument</code>. The <code>argument</code> may also be a (non-0) <code>char const *</code>. 0 is
returned if the characters in the <code>string</code> object and in <code>argument</code> are
the same; a negative value is returned if the text in <code>string</code> is
    <a name="an306"></a>
 lexicographically <em>before</em> the text in
<code>argument</code>; a positive value is returned if the text in <code>string</code> is
lexicographically <em>beyond</em> the text in <code>argument</code>.</blockquote>
<p>
<li><code>int string::compare(size_type opos, size_type on, string
argument)</code>:
    <blockquote>This member function can be used to compare a substring of the text
stored in the <code>string</code> object with the text stored in <code>argument</code>. At most
<code>on</code> characters, starting at offset <code>opos</code>, are compared with the text in
<code>argument</code>. The <code>argument</code> may also be a (non-0) <code>char const *</code>.</blockquote>
<p>
<li><code>int string::compare(size_type opos, size_type on, string
argument,</code>  <code>size_type apos, size_type an)</code>:
    <blockquote>This member function can be used to compare a substring of the text
stored in the <code>string</code> object with a substring of the text stored in
<code>argument</code>. At most <code>on</code> characters of the <code>string</code> object, starting at
offset <code>opos</code>, are compared with at most <code>an</code> characters of <code>argument</code>,
starting at offset <code>apos</code>.  Note that <code>argument</code> <em>must</em> also be a
<code>string</code> object.</blockquote>
<p>
<li><code>int string::compare(size_type opos, size_type on,
char const *argument,</code>  <code>size_type an)</code>:
    <blockquote>This member function can be used to compare a substring of the text
stored in the <code>string</code> object with a substring of the text stored in
<code>argument</code>. At most <code>on</code> characters of the <code>string</code> object, starting at
offset <code>opos</code>, are compared with at most <code>an</code> characters of
<code>argument</code>. <code>Argument</code> must have at least <code>an</code> characters. However, the
characters may have arbitrary values: the ASCII-Z value has no special
meaning.</blockquote>
<p>
<li> <a name="an307"></a>

   <code>size_type string::copy(char *argument, size_type on, size_type opos)</code>:
            <blockquote>The contents of the <code>string</code> object is (partially) copied
to <code>argument</code>.
    <ul>
    <li> If  <code>on</code> is provided, it refers to the maximum
number of characters that will be copied. If omitted, all the <code>string</code>'s
characters, starting at offset <code>opos</code>, will be copied to <code>argument</code>. Also,
<code>string::npos</code> may be specified to indicate that all available characters
should be copied.
    <li> If both <code>on</code> and <code>opos</code> are provided, <code>opos</code> refers to the
offset in the <code>string</code> object where copying should start.
    </ul>
    The actual number of characters that were copied is returned.
    Note: <em>following the copying, no <a name="an308"></a>
<code>ASCII-Z</code> will be appended to the
copied string</em>. A final ASCII-Z character can be appended to the copied text
using the following construction:
        <pre>
    buffer[s.copy(buffer)] = 0;
</pre>
</blockquote>
<p>
<li> <a name="an309"></a>
 <code>char const *string::c_str()</code>:
            <blockquote>the member function returns the contents of the <code>string</code>
object as an <code>ASCII-Z</code> <strong>C</strong>-string.</blockquote>
<p>
<li> <a name="an310"></a>
 <code>char const *string::data()</code>:
            <blockquote>returns the raw text stored in the <code>string</code> object. Since
this member does not return an ascii-Z string (as <code>c_str()</code> does), it can be
used to store and retrieve any kind of information, including, e.g., series of
0-bytes:
        <pre>
        string s;
        s.resize(2);
        cout &lt;&lt; static_cast&lt;int&gt;(s.data()[1]) &lt;&lt; endl;
</pre>
            </blockquote>
<p>
<li> <a name="an311"></a>
 <code>bool string::empty()</code>:
            <blockquote>returns <code>true</code> if the <code>string</code> object contains no data.</blockquote>
<p>
<li> <a name="an312"></a>

            <code>string &amp;string::erase(size_type opos; size_type on)</code>:
            <blockquote>This member function can be used to erase (a sub)string of
the <code>string</code> object.
            <ul>
            <li> If no arguments are provided, the contents of the <code>string</code>
object are completely erased.
            <li> If <code>opos</code> is specified, the contents of the <code>string</code>
object are erased, starting from index position <code>opos</code> until (including)
the object's final character.
            <li> If <code>on</code> is provided as well, <code>on</code> characters of
the <code>string</code> object, starting at index position <code>opos</code> are erased.
            </ul>
            </blockquote>
<p>
<li><code>iterator string::erase(iterator obegin, iterator oend)</code>:
            <blockquote>
        <ul>
        <li> If only <code>obegin</code> is provided, the <code>string</code> object's character
at iterator position <code>obegin</code> is erased.
        <li> If <code>oend</code> is provided as well, the range of characters of the
<code>string</code> object, implied by the <code>iterators obegin</code> and <code>oend</code> are
erased.
        </ul>
        The iterator <code>obegin</code> is returned, pointing to the character
immediately following the last erased character.</blockquote>
<p>
<li> <a name="an313"></a>

            <code>size_type string::find(string argument, size_type opos)</code>:
            <blockquote>Returns the index in the <code>string</code> object where
<code>argument</code> is found.
        <ul>
        <li> If <code>opos</code> is provided, it refers to the
index in the <code>string</code> object where the search for <code>argument</code> should
start. If <code>opos</code> is omitted, searching starts at the beginning of the
<code>string</code> object.</ul></blockquote>
<p>
<li><code>size_type string::find(char const *argument, size_type opos,
                                    size_type an)</code>:
            <blockquote>Returns the index in the <code>string</code> object where
<code>argument</code> is found.
        <ul>
        <li> If <code>opos</code> is provided, it refers to the index in the
<code>string</code> object where the search for <code>argument</code> should start. If omitted,
the <code>string</code> object is scanned completely.
        <li> If <code>an</code> is provided as well, it indicates the number of
characters of <code>argument</code> that should be used in the search: it defines a
partial string starting at the beginning of <code>argument</code>. If omitted, all
characters in <code>argument</code> are used.
        </ul></blockquote>
<p>
<li><code>size_type string::find(char c, size_type opos)</code>:
            <blockquote> Returns the index in the <code>string</code> object where <code>c</code> is
found.
        <ul>
        <li> If <code>opos</code> is provided it refers to the index in the
<code>string</code> object where the search for the character should start. If omitted,
searching starts at the beginning of the <code>string</code> object.
        </ul></blockquote>
<p>
<li> <a name="an314"></a>

            <code>size_type string::find_first_of(string argument,
                                               size_type opos)</code>:
            <blockquote>Returns the index in the <code>string</code> object where any
character in <code>argument</code> is found.
        <ul>
        <li> If <code>opos</code> is provided, it refers to
the index in the <code>string</code> object where the search for <code>argument</code> should
start. If omitted, searching starts at the beginning of the <code>string</code>
object.</ul></blockquote>
<p>
<li><code>size_type string::find_first_of(char const *argument,
size_type opos,</code>  <code>size_type an)</code>:
            <blockquote>Returns the index in the <code>string</code> object where a character
of <code>argument</code> is found, no matter which character.
        <ul>
        <li> If <code>opos</code> is provided it refers to the index in the <code>string</code>
object where the search for <code>argument</code> should start. If omitted, the
<code>string</code> object is scanned completely.
        <li> If <code>an</code> is provided it indicates the number of characters of
the <code>char const *</code> argument that should be used in the search: it defines a
partial string starting at the beginning of the <code>char const *</code> argument. If
omitted, all of <code>argument</code>'s characters are used.
        </ul></blockquote>
<p>
<li><code>size_type string::find_first_of(char c, size_type opos)</code>:
            <blockquote>Returns the index in the <code>string</code> object where character
<code>c</code> is found.
        <ul>
        <li> If <code>opos</code> is provided, it refers to the index in the <code>string</code>
object where the search for <code>c</code> should start. If omitted, searching starts
at the beginning of the <code>string</code> object.</ul></blockquote>
<p>
<li> <a name="an315"></a>

        <code>size_type string::find_first_not_of(string argument,
                                                size_type opos)</code>:
            <blockquote>Returns the index in the <code>string</code> object where a character
not appearing in <code>argument</code> is found.
        <ul>
        <li> If <code>opos</code> is provided, it refers to the index in the <code>string</code>
object where the search for <code>argument</code> should start.
        If omitted, searching starts at the beginning of the <code>string</code>
object.
        </ul></blockquote>
<p>
<li><code>size_type string::find_first_not_of(char const *argument,
size_type opos, size_type an)</code>:
            <blockquote>Returns the index in the <code>string</code> object where any
character <em>not</em> appearing in <code>argument</code> is found.
        <ul>
        <li> If <code>opos</code> is provided it refers to the index in the <code>string</code>
object where the search for characters not specified in <code>argument</code> should
start. If omitted, the <code>string</code> object is scanned completely.
        <li> If <code>an</code> is provided it indicates the number of characters of
the <code>char const *</code> argument that should be used in the search: it defines a
partial string starting at the beginning of the <code>char const *</code> argument. If
omitted, all of <code>argument</code>'s characters are used.
        </ul></blockquote>
<p>
<li><code>size_type string::find_first_not_of(char c, size_type opos)</code>:
            <blockquote>Returns the index in the <code>string</code> object where another
character than <code>c</code> is found.
        <ul>
        <li> If <code>opos</code> is provided, it refers to the index in the <code>string</code>
object where the search for <code>c</code> should start.  If omitted, searching starts
at the beginning of the <code>string</code> object.
        </ul></blockquote>
<p>
<li> <a name="an316"></a>

          <code>size_type string::find_last_of(string argument, size_type opos)</code>:
            <blockquote>Returns the <em>last</em> index in the <code>string</code> object where
one of <code>argument</code>'s characters is found.
        <ul>
        <li> If <code>opos</code> is provided it refers to the index in the <code>string</code>
object where the search for <code>argument</code> should start, proceeding backwards to
the <code>string</code>'s first character. If omitted, searching starts at the the
<code>string</code> object's last character.
        </ul></blockquote>
<p>
<li><code>size_type string::find_last_of(char const* argument,
size_type opos,</code>  <code>size_type an)</code>:
            <blockquote>Returns the last index in the <code>string</code> object where one of
<code>argument</code>'s characters is found.
        <ul>
        <li> If <code>opos</code> is provided it refers to the index in the <code>string</code>
object where the search for <code>argument</code> should start, proceeding backwards to
the <code>string</code>'s first character. If omitted, searching starts at the the
<code>string</code> object's last character.
        <li> If <code>an</code> is provided it indicates the number of characters of
<code>argument</code> that should be used in the search: it defines a
partial string starting at the beginning of the <code>char const *</code> argument. If
omitted, all of <code>argument</code>'s characters are used.
        </ul></blockquote>
<p>
<li><code>size_type string::find_last_of(char c, size_type opos)</code>:
            <blockquote>Returns the last index in the <code>string</code> object where
character <code>c</code> is found.
        <ul>
        <li> If <code>opos</code> is provided it refers to the index in the <code>string</code>
object where the search for character <code>c</code> should start, proceeding backwards
to the <code>string</code>'s first character. If omitted, searching starts at the the
<code>string</code> object's last character.
        </ul></blockquote>
<p>
<li> <a name="an317"></a>

        <code>size_type string::find_last_not_of(string argument,
size_type opos)</code>:
            <blockquote>Returns the last index in the <code>string</code> object where any
character not appearing in <code>argument</code> is found.
        <ul>
        <li> If <code>opos</code> is provided it refers to the index in the <code>string</code>
object where the search for characters not appearing in <code>argument</code> should
start, proceeding backwards to the <code>string</code>'s first character. If omitted,
searching starts at the the <code>string</code> object's last character.
        </ul></blockquote>
<p>
<li><code>size_type string::find_last_not_of(char const *argument,
            size_type</code>  <code>opos, size_type an)</code>:
            <blockquote>Returns the last index in the <code>string</code> object where any
character not appearing in <code>argument</code> is found.
        <ul>
        <li> If <code>opos</code> is provided it refers to the index in the <code>string</code>
object where the search for characters not appearing in <code>argument</code> should
start, proceeding backwards to the <code>string</code>'s first character. If omitted,
searching starts at the the <code>string</code> object's last character.
        <li> If <code>an</code> is provided it indicates the number of characters of
<code>argument</code> that should be used in the search: it defines a
partial string starting at the beginning of the <code>char const *</code> argument. If
omitted, all of <code>argument</code>'s characters are used.
        </ul></blockquote>
<p>
<li><code>size_type string::find_last_not_of(char c, size_type opos)</code>:
            <blockquote>Returns the last index in the <code>string</code> object where
another character than <code>c</code> is found.
        <ul>
        <li> If <code>opos</code> is provided it refers to the index in the <code>string</code>
object where the search for a character unequal to character <code>c</code> should
start, proceeding backwards to the <code>string</code>'s first character. If omitted,
searching starts at the the <code>string</code> object's last character.
        </ul></blockquote>
<p>
<li> <a name="an318"></a>

            <code>istream &amp;getline(istream &amp;istr, string object, char delimiter)</code>:
            <blockquote>This function (note that it's not a <em>member</em> function of
the class <code>string</code>) can be used to read a line of text from <code>istr</code>. All
characters until <code>delimiter</code> (or the end of the stream, whichever comes
first) are read from <code>istr</code> and are stored in <code>object</code>. The delimiter,
when present, is removed from the stream, but is not stored in <code>line</code>.  The
delimiter's default value is <code>'\n'</code>.<br>
    If the delimiter is not found, <code>istr.fail()</code> returns 1 (see section
<a href="cplusplus05.html#IOSTATES">5.3.1</a>).  Note that the contents of the last line, whether or not it
was terminated by a delimiter, will always be assigned to <code>object</code>.<br>
        </blockquote>
<p>
<li> <a name="an319"></a>

            <code>string &amp;string::insert(size_type opos, string argument,
size_type</code>  <code>apos, size_type an)</code>:
            <blockquote>This member function can be used to insert (a sub)string of
<code>argument</code> into the <code>string</code> object, <em>at</em> the <code>string</code> object's index
position <code>opos</code>. The arguments <code>apos</code> and <code>an</code> must either be specified
or they must both be omitted. If specified, <code>an</code> characters of <code>argument</code>,
starting at index position <code>apos</code> are inserted into the <code>string</code>
object. <br>
    If <code>argument</code> is of type <code>char const *</code>, no parameter <code>apos</code> is
available.  So, with <code>char const *</code> arguments, either <em>all</em> characters or
an <em>initial subset</em> of <code>an</code> characters of the provided <code>char const *</code>
argument are inserted into the <code>string</code> object. In this case, the prototype
of the member function is:
        <pre>
    string &amp;string::insert(size_type opos, char const *argument,
                           size_type an)
</pre>
        (As before, an implicit conversion from <code>char const *</code> to <code>string</code>
will occur if <code>apos</code> and <code>an</code> <em>are</em> provided).
        </blockquote>
<p>
<li><code>string &amp;string::insert(size_type opos, size_type n, char c)</code>:
        <blockquote>Using this member function, <code>n</code> characters <code>c</code> can be
inserted to the <code>string</code> object.</blockquote>
<p>
<li><code>iterator string::insert(iterator obegin, char c)</code>:
            <blockquote>The character <code>c</code> is inserted at the (iterator) position
<code>obegin</code> in the <code>string</code> object. The iterator <code>obegin</code> is returned.</blockquote>
<p>
<li><code>iterator string::insert(iterator obegin, size_type n, char c)</code>:
            <blockquote>At the (iterator) position <code>obegin</code> of <code>object</code> <code>n</code>
characters <code>c</code> are inserted. The iterator <code>obegin</code> is returned.</blockquote>
<p>
<li><code>iterator string::insert(iterator obegin,
InputIterator abegin,</code> <code>InputIterator aend)</code>:
            <blockquote>The range of characters implied by the <code>InputIterators
abegin</code> and <code>aend</code> are inserted at the (iterator) position <code>obegin</code> in
<code>object</code>. The iterator <code>obegin</code> is returned.</blockquote>
<p>
<li> <a name="an320"></a>
 <code>size_type string::length()</code>:
            <blockquote>returns the number of characters stored in the <code>string</code>
object.</blockquote>
<p>
<li> <a name="an321"></a>
 <code>size_type string::max_size()</code>:
            <blockquote>returns the maximum number of characters that can be stored
in the <code>string</code> object.</blockquote>
<p>
<li> <a name="an322"></a>

        <code>string &amp;string::replace(size_type opos, size_type on, string
argument,</code> <code>size_type apos, size_type an)</code>:
            <blockquote>The arguments <code>apos</code> and <code>an</code> are optional. If omitted,
<code>argument</code> is considered completely.  The substring of <code>on</code> characters of
the <code>string</code> object, starting at position <code>opos</code> is replaced by
<code>argument</code>.   If <code>on</code> is set to 0, the member function
<em>inserts</em> <code>argument</code> into <code>object</code>.<br>
            <ul>
                <li> If <code>apos</code> and <code>an</code> are provided, <code>an</code> characters of
<code>argument</code>, starting at index position <code>apos</code> will replace the indicated
range of characters of <code>object</code>.</ul>
    If <code>argument</code> is of type <code>char const *</code>, no parameter <code>apos</code> is
available.  So, with <code>char const *</code> arguments, either <em>all</em> characters or
an <em>initial subset</em> of the characters of <code>an</code> characters of the provided
<code>char const *</code> argument will replace the indicated range of characters in
<code>object</code>. In that case, the prototype of the member function is:
        <pre>
    string &amp;string::replace(size_type opos, size_type on,
                            char const *argument, size_type an)
</pre>
            </blockquote>
<p>
<li><code>string &amp;string::replace(size_type opos, size_type on,
            size_type n,</code>  <code>char c)</code>:
            <blockquote>This member function can be used to replace <code>on</code>
characters of the <code>string</code> object, starting at index position <code>opos</code>, by
<code>n</code> characters having values <code>c</code>.</blockquote>
<p>
<li><code>string &amp;string::replace (iterator obegin, iterator oend, string
argument)</code>:
            <blockquote>Here, the string implied by the iterators <code>obegin</code> and
<code>oend</code> are replaced by <code>argument</code>. If <code>argument</code> is a <code>char const *</code>,
an extra argument <code>n</code> may be used, specifying the number of characters of
<code>argument</code> that are used in the replacement.</blockquote>
<p>
<li><code>string &amp;string::replace(iterator obegin, iterator oend,
size_type n, char c)</code>:
            <blockquote>The range of characters of the <code>string</code> object, implied by
the <code>iterators obegin</code> and <code>oend</code> are replaced by <code>n</code> characters having
values <code>c</code>.</blockquote>
<p>
<li><code>string string::replace(iterator obegin, iterator oend,
InputIterator abegin, InputIterator aend)</code>:
            <blockquote>Here the range of characters implied by the iterators
<code>obegin</code> and <code>oend</code> is replaced by the range of characters implied by the
<code>InputIterators abegin</code> and <code>aend</code>.</blockquote>
<p>
<li> <a name="an323"></a>
 <code>void string::resize(size_type n, char c)</code>:
            <blockquote>The string stored in the <code>string</code> object is resized to
<code>n</code> characters. The second argument is optional, in which case the value
<code>c = 0</code> is used. If provided and the string is enlarged, the extra
characters are initialized to <code>c</code>.</blockquote>
<p>
<li> <a name="an324"></a>

            <code>size_type string::rfind(string argument, size_type opos)</code>:
            <blockquote>Returns the index in the <code>string</code> object where
<code>argument</code> is found. Searching proceeds either from the end of the
<code>string</code> object or from its offset <code>opos</code> back to the beginning. If the
argument <code>opos</code> is omitted, searching starts at the end of <code>object</code>.</blockquote>
<p>
<li><code>size_type string::rfind(char const *argument, size_type opos,
size_type an)</code>:
            <blockquote>Returns the index in the <code>string</code> object where
<code>argument</code> is found. Searching proceeds either from the end of the
<code>string</code> object or from offset <code>opos</code> back to the beginning.  The
parameter <code>an</code> indicates the number of characters of <code>argument</code> that
should be used in the search: it defines a partial string starting at the
beginning of <code>argument</code>. If omitted, all characters in <code>argument</code> are
used.</blockquote>
<p>
<li><code>size_type string::rfind(char c, size_type opos)</code>:
            <blockquote> Returns the index in the <code>string</code> object where <code>c</code> is
found.   Searching proceeds either from the end of the
<code>string</code> object or from offset <code>opos</code> back to the beginning.</blockquote>
<p>
<li> <a name="an325"></a>
 <code>size_type string::size()</code>:
            <blockquote>returns the number of characters stored in the <code>string</code>
object. This member is a synonym of <code>string::length()</code>.</blockquote>
<p>
<li> <a name="an326"></a>

            <code>string string::substr(size_type opos, size_type on)</code>:
            <blockquote>Returns (using a <em>value</em> return type) a substring of the
<code>string</code> object. The parameter <code>on</code> may be used to specify the number of
characters of <code>object</code> that are returned. The parameter <code>opos</code> may be used
to specify the index of the first character of <code>object</code> that is
returned. Either <code>on</code> or both arguments may be omitted. The string
<code>object</code> itself is not modified by <code>substr()</code>.</blockquote>
<p>
<li> <a name="an327"></a>

            <code>size_type string::swap(string argument)</code>:
            <blockquote>swaps the contents of the <code>string</code> object and
<code>argument</code>. In this case, <code>argument</code> must be a <code>string</code> and cannot be a
<code>char const *</code>. Of course, both strings (<code>object</code> and <code>argument</code>) are
modified by this member function.</blockquote>
        </ul>
<p>

<hr>
<ul>
    <li> <a href="cplusplus.html">Table of Contents</a>
    <li> <a href="cplusplus03.html">Previous Chapter</a>
    <li> <a href="cplusplus05.html">Next Chapter</a>
</ul>
<hr>
</body>
</html>
